RAVE/YAEL 3D Viewer (Basics)

Prerequisites

This post assumes that you have already imported subject’s imaging data to RAVE and finished the electrode localization. If you haven’t done so, please check (TODO) for instructions.

This post uses default demo subject. Please run the following code block

library(raveio)
project_demo <- as_rave_project("demo", strict = FALSE)
if(!"DemoSubject" %in% project_demo$subjects()) {
  # missing demo subject, install
  message("Missing `DemoSubject`. Downloading...")
  install_subject("DemoSubject")
}

1. Simple 3D viewer

Library raveio provides simple high-level function rave_brain to load 3D brain object.

brain <- raveio::rave_brain("demo/DemoSubject")
# See the output to the right for what's inside of the brain object
brain

Subject - DemoSubject 
Transforms:

- FreeSurfer TalXFM [from scanner to MNI305]:
          [,1]      [,2]     [,3]       [,4]
[1,]  1.071608 -0.069364 0.003839  -5.186203
[2,] -0.033422  1.293478 0.133732 -26.001312
[3,]  0.039658 -0.231380 1.268464 -21.980759
[4,]  0.000000  0.000000 0.000000   1.000000

- Torig [Voxel IJK/CRS to FreeSurfer space tkrRAS, vox2ras-tkr]
     [,1] [,2] [,3] [,4]
[1,]   -1    0    0  128
[2,]    0    0    1 -128
[3,]    0   -1    0  128
[4,]    0    0    0    1

- Norig [Voxel IJK/CRS to Scanner space, vox2ras]
     [,1] [,2] [,3]      [,4]
[1,]   -1    0    0  131.6145
[2,]    0    0    1 -127.5000
[3,]    0   -1    0  127.5000
[4,]    0    0    0    1.0000

- Scanner origin in FreeSurfer tkrRAS coordinate
[1] -3.614471 -0.500000  0.500000

- FreeSurfer RAS to MNI305, vox2vox-MNI305
          [,1]      [,2]     [,3]       [,4]
[1,]  1.071608 -0.069364 0.003839  -1.349508
[2,] -0.033422  1.293478 0.133732 -25.542242
[3,]  0.039658 -0.231380 1.268464 -22.587338
[4,]  0.000000  0.000000 0.000000   1.000000
Surface information (total count 1)
  pial [ fs ]  
Volume information (total count 1)
  T1  

Use brain$plot(<your arguments...>) to show the viewer:

brain$plot()

Preview of the result. See below if you want to play with the 3D viewer interactively

2. Render electrodes with values

brain$set_electrode_values(table_or_path) allows users to load a data table and render electrodes with colors. Users can create a csv table using Excel or their favorite programming languages, as long as the table follows the following format:

Subject	Electrode	varname*
DemoSubject	1	0.25
DemoSubject	14	-0.4
…	…	…

The column names are case-sensitive

• Subject is the subject code
• Electrode is the electrode channel number (integer)
• varname* can be almost anything (give it a meaningful name, for e.g., Power, Cluster, …) that you would like to show, and the values can be either numeric or categorical
  • The variable name is recommended to only contain letters and digits. For example, BetaBandPower seems to be a good idea, while names like 75-150 Hz should be avoided
  • The variable values must not be numerical if the intent is categorical. For example cluster values such as 1, 2, 3, … should be avoided and users should use Cluster 1, Cluster 2, Cluster 3, …, or A, B, C, … instead

# Method 1: `csv_path` is the string of path to the csv
brain$set_electrode_values(csv_path)

# Method 2: use data frame
table <- read.csv(csv_path)
brain$set_electrode_values(table)

brain$plot()

Left: continuous values with symmetric value range. The color palette transition from blue to white to red (default); Right: Categorical data with default color palette

3. Render options

brain$plot allows users to provide render options to change the following components:

• Color palette
• Default value ranges (for continuous data)
• Control panels

Here’s an example

# Load brain
brain <- raveio::rave_brain("demo/DemoSubject")

# Set values with 2 variables: `ContinuousVal` and `CategoricalVal`
brain$set_electrode_values(
  data.frame(
    Subject = "DemoSubject",
    Electrode = c(13:16,24,73:80),
    ContinuousVal = rnorm(13),
    CategoricalVal = sample(letters[1:4], size = 13, replace = TRUE),
    PValue = c(0.15, 0.5, 0.9, 0.01, 0.05, 0.45, 0.8,
               0.68, 0.6, 0.33, 0.001, 0.36, 0.83)
  )
)

# Plot brain with options
brain$plot(
  
  # change color palettes: each variable requires a palette (if not default)
  palettes = list(
    
    # discrete values require each category to be filled with a 
    # color. The order is alphabetic
    CategoricalVal = c("red", "blue", "green"),
    
    # continuous values requires at least 2 key colors
    ContinuousVal = c("white", "purple"),
    
    # p-value is not linearly scaled, R provides `colorRampPalette`
    # to generate non-linear color palette from at least 
    # 3 key colors. 
    # This example used 5 key colors with bias = 2 so the
    PValue = colorRampPalette(
      c("red", "yellow", "cyan", "gray", "gray"), bias = 2
    )(100)
    
  ),
  
  # Change value range: sets the value range for variables that have
  # bounded ranges, such as p-values
  value_ranges = list(
    
    # p-value should range from 0-1 
    PValue = c(0, 1),
    
    # We also want to trim the `ContinuousVal` to 95% CI
    ContinuousVal = c(-2, 2)
    
  ),
  
  # Set initial controller status
  controllers = list(
    
    # Display p-value 
    "Display Data" = "PValue",
    
    
    # Overlay atlases from side canvas
    "Voxel Type" = "aparc_aseg",
    "Voxel Display" = "side camera",
    
    # Overlay axial slices with surfaces
    "Overlay Axial" = TRUE,
    
    # Set surface opacity
    "Left Opacity" = 0.4,
    "Left Mesh Clipping" = 0.3,
    "Right Opacity" = 0.4,
    "Right Mesh Clipping" = 0.3,
    
    # Electrode outline
    "Outlines" = "on",
    "Translucent" = "contact+outline",
    
    # Background color and camera position
    "Background Color" = "#000000",
    "Camera Position" = "superior"
    
  ),
  
  # Custom javascript for advanced users
  custom_javascript = r"[
  app.$wrapper.parentNode.style.width="100%";
  app.$wrapper.parentNode.style.height="600px";
  app.canvas.side_width = 160;
  app.canvas.sideCanvasList.coronal.reset();
  app.canvas.sideCanvasList.axial.reset();
  app.canvas.sideCanvasList.sagittal.reset();
  app.resize()
  ]"
)

Key Documentations

Function rave_brain

Load ‘FreeSurfer’ or ‘AFNI/SUMA’ brain from ‘RAVE’

rave_brain

Description

Create 3D visualization of the brain and visualize with modern web browsers

Usage

rave_brain(
  subject,
  surfaces = "pial",
  use_141 = TRUE,
  recache = FALSE,
  clean_before_cache = FALSE,
  compute_template = FALSE,
  usetemplateifmissing = FALSE,
  include_electrodes = TRUE
)

Arguments

subject	character, list, or RAVESubject instance; for list or other objects, make sure subject$subject_id is a valid ‘RAVE’ subject ‘ID’
surfaces	one or more brain surface types from “pial”, “white”, “smoothwm”, “pial-outer-smoothed”, etc.; check freesurfer_brain2
use_141	whether to use ‘AFNI/SUMA’ standard 141 brain
recache	whether to re-calculate cache; only should be used when the original ‘FreeSurfer’ or ‘AFNI/SUMA’ files are changed; such as new files are added
clean_before_cache	whether to clean the original cache before recache; only set it to be true if original cached files are corrupted
compute_template	whether to compute template mappings; useful when template mapping with multiple subjects are needed
usetemplateifmissing	whether to use template brain when the subject brain files are missing. If set to true, then a template (usually ‘N27’) brain will be displayed as an alternative solution, and electrodes will be rendered according to their ‘MNI305’ coordinates, or ‘VertexNumber’ if given.
include_electrodes	whether to include electrode in the model; default is true

Value

A ‘threeBrain’ instance if brain is found or usetemplateifmissing is set to true; otherwise returns NULL

Examples

# Please make sure DemoSubject is correctly installed
# The subject is ~1GB from Github

if(interactive()){
  brain <- rave_brain("demo/DemoSubject")

  if( !is.null(brain) ) { brain$plot() }

}